<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Understanding Bundles and Elements</title>
<meta name="GENERATOR" content="WinCHM">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

</head>

<body>

<p>ResourceBlender uses bundles and elements to represent localized elements in an application. How these are used depends on the output format of that project.</p>
<img src="images/600px-Rb_bundles_elements.png" alt="Bundles, elements and resources" class="centered" />
<p>Applications in ResourceBlender can contain multiple bundles. Each bundle is unique (though the same name can be used for bundles in different applications), and elements. Each element is assigned a resource, which can be shared by many elements. When outputting to a resource format, the translations for each resource are used to create files for each language. This varies depending on the output format.</p>

<div class="contents">
  <h2>Contents</h2>
  <ol>
      <li><a href="#bundles">Bundles</a>
          <ol>
              <li><a href="#bundles-java">Java</a></li>
              <li><a href="#bundles-net">.NET</a></li>
              <li><a href="#bundles-fx">Firefox</a></li>
              <li><a href="#bundles-php">PHP Definitions / PHP Array</a></li>
          </ol>
      </li>
      <li><a href="#elements">Elements</a>
          <ol>
              <li><a href="#elements-java">Java</a></li>
              <li><a href="#elements-net">.NET</a></li>
              <li><a href="#elements-fx">Firefox</a></li>
              <li><a href="#elements-phpdefinitions">PHP Definitions</a></li>
              <li><a href="#elements-phparray">PHP Array</a></li>
          </ol>
      </li>
      <li><a href="#resources">Resources</a></li>
  </ol>
</div>

<h2><a name="bundles">Bundles</a></h2>
<p>Bundles are containers for groups of elements.</p>
<h3><a name="bundles-java">Java</a></h3>
<p>Java projects use the bundle name together with the language code to generate the name of the .properties file. <strong>For example:</strong> A bundle called <em>resources</em> in an application which used the languages English and German would generate two files - <em><span style="color:#EF0E0E;">resources</span>_<span style="color:#1B1675;">en</span>.properties</em> and <em><span style="color:#EF0E0E;">resources</span>_<span style="color:#1B1675;">de</span>.properties</em>.</p>
<h3><a name="bundles-net">.NET</a></h3>
<p>.NET uses bundles to represent forms. <strong>For example:</strong> A bundle called <em><span style="color:#EF0E0E;">FrmMain</span></em> in an application which used English (language code=<span style="color:#1B1675;">en</span>) and Czech (language code=<span style="color:#1B1675;">cs</span>) would generate <em><span style="color:#EF0E0E;">FrmMain</span>.<span style="color:#1B1675;">en</span>.resx</em> and <em><span style="color:#EF0E0E;">FrmMain</span>.<span style="color:#1B1675;">cs</span>.resx</em>. .NET can also make use of generic bundles which can be used by any class by creating a new <em>ResourceManager</em> object.</p>
<h3><a name="bundles-fx">Firefox</a></h3>
<p>Firefox uses two bundles, JavaScript and XUL. JavaScript bundles are just Java .properties files, XUL bundles are .dtd document type definitions containing entities. For more information on the format used for Firefox extensions, see <a href="http://developer.mozilla.org/En">Mozilla's MDC</a>.</p>
<h3><a name="bundles-php">PHP Definitions / PHP Array</a></h3>
<p>The template provided by default uses the bundle name and language code to generate the filename. Eg: <em><span style="color:#EF0E0E;">MainStrings</span>_<span style="color:#1B1675;">en-GB</span>.php</em>.</p>

<h2><a name="elements">Elements</a></h2>
<p>Elements represent a single object in a resource bundle or form. Each element must be assigned a resource.</p>
<h3><a name="elements-java">Java</a></h3>
<p>In Java applications, the element name is used in calls to the <em>getString</em> method of <em>ResourceBundle</em>.</p>
<p><strong>For example:</strong> To access an element called <em><span style="color:#158F00;">MainMenuText</span></em> in a bundle called <em><span style="color:#EF0E0E;">myresources</span></em>, first initialize a new ResourceBundle using</p>
<pre>ResourceBundle res = new ResourceBundle.getBundle("myresources", new Locale(country, locale));</pre><p>then use</p><pre>String menuText = res.getString("MainMenuText");</pre>
<h3><a name="elements-net">.NET</a></h3>
<p>.NET handles compilation of bundles automatically when a form is localized. First, the form's <em>localizable</em> property needs to be set to true, then the resources just need to be dropped in to the source folder after generation. Element names comprise of the names of controls on a form and their properties. To localize the text displayed on a button called <em>btnDoSomething</em>, create an element called <em><span style="color:#158F00;">btnDoSomething.Text</span></em>. Localized resources can also be accessed programatically using <em>ResourceManager</em>.</p>
<h3><a name="elements-fx">Firefox</a></h3>
<p>Firefox extensions access bundles using nsIStringBundleService/nsIStringBundle or the &lt;stringbundle&gt; tag. Elements in the XUL bundle are accessed by <em>&amp;elementName;</em>, while JavaScript elements can be accessed by calling .getString() on nsIStringBundle.</p>
<h3><a name="elements-phpdefinitions">PHP Definitions</a></h3>
<p>Each element is defined as a constant. After the file has been include()d, the translation can be used as any other constants.</p>
<pre>echo ElementName;</pre>
<h3><a name="elements-phparray">PHP Array</a></h3>
<p>Element are defined as keys in an array, translations are the values. After the file has been include()d, use </p>
<pre>echo $BundleName['ElementName'];</pre>

<h2><a name="resources">Resources</a></h2>
<p>Resources are strings of text in one or more languages. Each resource contains at least one language, and contains translations from that language into other languages.</p>

</body>
</html>

